Skip to main content

Navigating Gem5

gem5 is big. Reallly, big. Due to that, it can get confusing when you need to find a feature and change it. The purpose of this document is to provide some pointers and information about what the gem5 environment looks like and some common directories you should be aware of.

Directory Structure​

$GEM_PATH
├── build  // Where the program hides
├── build_opts
├── build_tools
├── configs  // $GEM_CONFIGS
├── ext
├── include
├── site_scons
├── src  // $GEM_SRC the   m e a t y   part
├── system
├── tests
└── util  // You'll need this eventually

There are four key directories, as highlighted:

  • build
  • configs
  • src
  • util

You can pretty much* ignore everything else.

note: *

These are just the directories I find myself diving into the most. If you really want to use this for doing Epic Cool Stuff™, then eventually you'll probably have to play around a bit, but for this class, these are the most important.

The src Directory​

When we enter src, we get to see the wonderfully convoluted source code of gem5:

$GEM_SRC
├── arch  // architecture specific
├── base  // simulator infrastructure for stats, program loader etc...
├── cpu   // code for CPU behaviours
├── dev   // I'm honestly not sure
├── doc
├── doxygen
├── gpu-compute // GPU module
├── kern  // for FS mode (load and run OS, the usual)
├── learning_gem5 // tutorial materials
├── mem   // memory behaviour code
├── proto // protobuf*
├── python // python bindings for SimObjects
├── sim   // More simulator infrastructure
├── sst   // Single Stream Transport
└── systemc // SE mode emulation utilities (to verify)

Once again, some key directories:

  • cpu: all the source files for processor behaviour (predictors, out of order (O3) behaviours, etc.)
  • mem: all the source files for memory behaviour (cache coherence, line size, etc.)
  • python: the source files for interfacing with all objects through the run scripts (in python)

The configs Directory​

This directory contains run scripts for a variety of pre-made and woking gem5 configurations. This includes multi-level cache hierarchy, multicore processors and the rest of the gang. There are files specifically dedicated to RISCV processors, however you should note that most characteristics from other architectures can be easily transferred to a RISCV processor as well.

The build Directory​

This directory serves to store your compiled version of gem5, that's really the only thing of note here.

The utils Directory​

This directory contains tools that you will need to analyze output and information provided by the simulator. Some of the interesting ones include:

  • o3-pipeview.py: This allows you to analyze the pipeline occupancy of the processor at a given time
  • decode_inst_dep_trace.py: Allows the analysis of instruction dependency tracing in the simulation
  • on-chip-network-power-area.py: If you set it up correctly, this can analyze the power consumption of different chip components